Skip to content

Collapse WORKFLOW.md 5A to a Procedure and an Evidence Rule - #1394

Merged
ptr727 merged 4 commits into
developfrom
feature/collapse-5a-to-evidence-map
Sep 6, 2026
Merged

Collapse WORKFLOW.md 5A to a Procedure and an Evidence Rule#1394
ptr727 merged 4 commits into
developfrom
feature/collapse-5a-to-evidence-map

Conversation

@ptr727

@ptr727 ptr727 commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Pull request 3 of the #1311 reshape sequence, and the third to ship after PR 1 (#1373) and PR 5 (#1392).

What it does

WORKFLOW.md 5A carried nine "Core" bullets restating section 4's D-guarantees and five per-type addenda, roughly 2400 words of a second hand-authored wording of the contract. It is now three paragraphs: how a verdict is recorded, where evidence lives when it is not in the workflow files, and how to cite it. Section 5 drops from about 3000 words to 1000.

A section that says where to look cannot disagree with the section that says what must hold, so 32 of #1370's 44 findings are unwritable rather than fixed: each quotes 5A text that no longer exists. The two finding classes step 14 measured, "5A contradicts or misstates the guarantee it audits" (15 items) and "unsupported check" (8 items), have no surface left to sit on.

Also fixed, from #1393

  • Item 15 (also Tracker: WORKFLOW.md > 5. Test Methodology #1370 items 2 and 44). S1 and S4 read "validate-release skipped (smoke), succeeds", one job with two conclusions. D2.2 makes the check exit early while the job succeeds, and warns against reading that as a job-level skip, which the old wording invited.
  • Item 10. S11 stated merge-bot auto-merge as the required output, contradicting D8.3's auto-merge: false tracker, which prefixes the head so no merge-bot rule matches.
  • Item 11 (also Tracker: WORKFLOW.md > 5. Test Methodology #1370 item 31). 5C's maintainer-only fence reached only a probe that dispatches or re-runs, so its first bullet told an agent to open a pull request on the repository it audits.
  • Items 12 and 13. The Assessment restated 5A's recording rule more narrowly than 5A states it, and spelled the N/A token two ways.

Swept to match: section 1's applicability rule and its two-layer bullet, section 6's three references to the deleted addenda, AUDIT.md sections 3 and 5 plus its flowchart node, and the audit-a-repo and workflow-ci-contract skills.

Review

Sixteen whole-unit carried-content passes over ten units and five diff passes, all on the strongest tier, before this pull request existed. They raised roughly 70 findings. Every one was on this change's own text or on a surface this change put in disagreement; none was against the collapse itself. All ten changed canonical units carry a recorded pass at their current text, and the local review receipt covers the final content.

The maintainer settled one design question mid-flight: an interim revision carried a per-guarantee evidence map, and it was deleted because a per-guarantee map is itself a hand-authored second surface and regenerated the same defect class it replaced, at smaller scale. That decision is what the current three-paragraph shape implements.

Known and filed, not fixed here

  • D6.2 now stands unqualified. The deleted 5A text was the sole home of its publisher exception, and the hub's own publisher stub in docs/reusable-workflows.md reads github.ref_name in four places. Moving the carve-out into D6.2 was attempted twice and withdrawn twice, each time on verified evidence that the wording was wrong. Section 4 is pull request 2's, and the evidence is filed for it.
  • 5B carries no counterpart to the pinned-SHA read. AUDIT.md and audit-a-repo now tell an auditor to read a called workflow at the SHA the caller pins, and 5A's citation rule admits that evidence, but 5B, where the job graph is actually walked, does not say it.
  • Two requirements had no home outside 5A. The pypi environment's deployment-branch rule, which Tracker: WORKFLOW.md > 5. Test Methodology #1370 item 43 shows would block every .dev0 develop publish D3.4 requires, is genuinely lost. The static-site generator's checksum pin survives as spec/project-types.json's hugo.generator.pinned.

Full disposition, including the section 6 and AUDIT.md items this review surfaced, is on #1370.

Refs #1311, #1370, #1393

🤖 Generated with Claude Code

ptr727 and others added 4 commits September 6, 2026 12:45
5A carried nine "Core" bullets restating section 4's D-guarantees and five
per-type addenda, roughly 2400 words of a second hand-authored wording of the
contract. It is now three paragraphs: how a verdict is recorded, where evidence
lives when it is not in the workflow files, and how to cite it.

A section that says where to look cannot disagree with the section that says
what must hold, so 32 of the 44 findings on the section 5 tracker are unwritable
rather than fixed: each quotes 5A text that no longer exists. Section 4 keeps
the requirement, together with whatever each guarantee defers to.

Also fixed, from the pre-existing backlog #1393 opened:

- S1 and S4 gave one job two conclusions in one cell. D2.2 makes the check exit
  early while the job succeeds, which is what the cells now say.
- S11 stated merge-bot auto-merge as the required output, contradicting D8.3's
  `auto-merge: false` tracker, which prefixes the head so no rule matches.
- 5C's maintainer-only fence reached only a probe that dispatches or re-runs, so
  its first bullet told an agent to open a pull request on the repo it audits.
- The Assessment restated 5A's recording rule more narrowly than 5A states it,
  and spelled the N/A token two ways.

Swept to match: section 1's applicability rule and its two-layer bullet, section
6's three references to the deleted addenda, `AUDIT.md` section 5, and the
`audit-a-repo` and `workflow-ci-contract` skills.

Two requirements had no home outside 5A and are filed rather than moved, since
each needs a decision about which guarantee should own it: the `pypi`
environment's deployment-branch rule, which #1370 item 43 shows would block
every `.dev0` develop publish D3.4 requires, and the static-site generator's
pin-by-version-and-checksum.

Refs #1370, #1393, #1311

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…amble

The preamble read "Which of its checks and scenarios bind a given repository",
which went stale when 5A stopped carrying checks. Calling them guarantees
instead made the sentence circular, since section 5 holds no guarantees and the
same sentence locates the D-guarantees in section 4.

It now names each half by where it lives, 5A's items and 5B's scenarios, so
neither noun claims section 5 owns guarantees and the 5A half of applicability
is no longer dropped. "Exercises" is the scenario table's own column word, where
"trace" takes the scenario as its object everywhere else in the section.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Six defects the whole-unit passes found in this change's own text.

S11 named the bump PR's head as `<prefix>-<branch>` before its fork, so the
claim was asserted on both legs, and D8.3 says an `auto-merge: false` tracker
prefixes the head so no merge-bot rule matches it. The cell now names the PR
without the prefix. Its expected output also restated D8.3's matching
obligation, which is the second home this change exists to remove, so the cell
states the two outcomes and cites the guarantee for the rule.

5A's citation forms were narrower than the evidence list two lines above them.
A composite action reached at the caller's pin lives in another repository, so
a bare `file:line` is wrong for it, and this fleet counts a secret name as its
own kind of evidence rather than as a repository setting. Both are covered now.
The evidence sentence also claimed every guarantee whose evidence lies outside
the workflow files names where, which D8.2 falsifies by naming no location for
`.github/dependabot.yml`.

The skill's applicability bullet qualified a 5B scenario as "tracing one"
guarantee, where S7 exercises five, and the qualifier invited tying a scenario's
applicability to its guarantee's, which section 5's own S9 rule contradicts.

The carried test-methodology preamble enumerated what section 5 holds in three
successive wordings that were stale, circular, and self-referential in turn. It
now names the section below as the subject and says its items and scenarios
answer to section 4's D-guarantees.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…Term

Section 1's applicability rule no longer names a 5A check, and three surfaces
still cited it for that word: AUDIT.md's gate, its own flowchart node, and the
audit-a-repo skill. Each now says "an item or check", marked as this audit's
extension of section 1 rather than as section 1's own text, since AUDIT.md
grades spec checks that section 1 says nothing about.

The audit-a-repo skill had tracked only half of AUDIT.md section 5's rule, the
citation form, and not the instruction to read a called workflow at the SHA the
caller pins. Without it the skill's own "read main as ground truth" was the
nearest branch rule, so an auditor would trace a job graph through the hub's
current main rather than the commit the audited repo runs.

The source-only walkthrough briefly recorded D4.6 and D5.6 N/A. Blog declares
["hugo", "source-only"], so that negated the static-site bullet for a live repo
and would have dropped the live-host assertion and the retention-ownership
check its committed report grades as passing. Its N/A list is now item-level,
D5.1-D5.5 and D6.1 and D6.3 rather than "D5/D6 artifact items", and names the
five build targets, so neither class can be read to cover the deploy surface.

Refs #1370, #1393, #1311

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Copilot AI lite review requested due to automatic review settings September 6, 2026 21:12
@qodo-code-review

Copy link
Copy Markdown

ⓘ Qodo reviews are paused because your trial has ended. Ask your workspace admin to add credits to resume reviews. Manage billing

@coderabbitai

coderabbitai Bot commented Sep 6, 2026

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Team

Run ID: 52b3b14c-8bcb-4c90-b4f4-493fb709c170


Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The edits consistently collapse 5A to procedure/evidence rules and the sweeps keep AUDIT.md and skill distributions aligned without introducing internal inconsistencies.

Pull request overview

This pull request collapses WORKFLOW.md section 5A from a large restated rule set into a concise procedure/evidence rule, then sweeps the audit procedure and the workflow-ci-contract/audit-a-repo skill surfaces to match.

Changes:

  • Rewrite WORKFLOW.md 5A to describe how to record/cite audit evidence rather than restating section 4 guarantees.
  • Update trace scenarios and probe wording to remove contradictory job-level “skipped (smoke), succeeds” language and clarify maintainer-only probes.
  • Sweep AUDIT.md, skill copies, and the canonical review ledger to reflect the new 5A shape and applicability phrasing.
File summaries
File Description
WORKFLOW.md Collapses 5A to an audit procedure + evidence rule; updates scenarios/probe text to match.
AUDIT.md Aligns applicability language and updates the “assert Actions implement WORKFLOW.md” step to cite pinned-call evidence.
reports/canonical-review.json Records updated whole-unit review stamps/digests for touched canonical units.
.agents/skills/workflow-ci-contract/SKILL.md Updates applicability/two-layer wording to reflect removal of “5A checks” as a separate surface.
.agents/skills/workflow-ci-contract/references/test-methodology.md Regenerates the included section 5 text with the collapsed 5A procedure/evidence rule.
.agents/skills/audit-a-repo/SKILL.md Updates measuring guidance to apply applicability to AUDIT.md checks and to read pinned-called workflows at their SHA.
.github/skills/workflow-ci-contract/SKILL.md Generated copy of the workflow-ci-contract skill updated to match source.
.github/skills/workflow-ci-contract/references/test-methodology.md Generated copy of the included methodology updated to match source.
.github/skills/audit-a-repo/SKILL.md Generated copy of the audit-a-repo skill updated to match source.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/SKILL.md Generated plugin skill copy updated to match source.
.claude-plugin/fleet-skills/skills/workflow-ci-contract/references/test-methodology.md Generated plugin include copy updated to match source.
.claude-plugin/fleet-skills/skills/audit-a-repo/SKILL.md Generated plugin skill copy updated to match source.
.claude-plugin/fleet-skills/.source-digests/workflow-ci-contract Updates source digest for the generated plugin workflow-ci-contract unit.
.claude-plugin/fleet-skills/.source-digests/audit-a-repo Updates source digest for the generated plugin audit-a-repo unit.
Review details
  • Files reviewed: 14/14 changed files
  • Comments generated: 0
  • Review effort level: Lite

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

@ptr727
ptr727 merged commit 8805379 into develop Sep 6, 2026
9 checks passed
@ptr727
ptr727 deleted the feature/collapse-5a-to-evidence-map branch September 6, 2026 21:23
ptr727 added a commit that referenced this pull request Sep 6, 2026
…e YAML Conventions (#1395)

Collapses pull requests 2, 4 and 6 of the #1311 sequence into one
change, which the maintainer
agreed to because the three touch the same surfaces and, run
sequentially, each would re-sweep what
the last swept and pay the seam cost three times.

## What it does

**#1206's two maintainer decisions, applied first**, since sections 4
and 6 and `GOVERNANCE.md` all
depend on them. D9 binds exactly as D1 through D8 do, so a style
violation is a defect and
`GOVERNANCE.md`'s target-state framing settles *when* an unswept
workflow is fixed rather than
*whether* the violation counts. An overlap resolves **by subject**
rather than by blanket
precedence, and every section 1 to 6 now has a named owner.

**Section 4's two longest items shrink to their outcomes**, D1.6 from
about 974 words and D4.5 from
about 602. Nothing is deleted: the Microsoft.Testing.Platform runner,
package floor and its
silently-green failure modes move to `dotnet-codestyle`, the
`pytest-cov` dependency and coverage
selector to `python-codestyle`, and the failed-push recovery routes to
`operational-vs-release-workflow`.

**Section 6 states only what each type adds, and carries no N/A list at
all.** All eight per-type
N/A lists are deleted rather than corrected, because such a list is
right for a single-type
repository and negates a construct a second declared type supplies,
which is the defect #1394
shipped through fifteen clean unit passes. Section 1's applicability
rule derives the N/A set
instead, so no row can take away what another row gives. Rows are added
for the seven registry
types that had none, `upstream-wrapper` is split out of `docker`, and
the construct table keys on
the construct being present rather than on a registry field.

**`GOVERNANCE.md` "Workflow YAML Conventions" is swept** for the items
on #1367.

## What is deliberately not done

- **D6.2's publisher exception stays withdrawn.** A fourth wording was
attempted here and
disproved by `get-version-task.yml`, a called workflow whose branch
classification comes from the
caller's `GITHUB_REF` exactly as D3.1 requires. The item returns to the
text `develop` carries and
  #1369 records all four disproofs.
- **No bullet-to-D-item mapping.** One was added here, proved wrong four
ways, drifted between its
two copies in the round that wrote it, and was deleted on the
maintainer's call.
- **No per-guarantee evidence map**, per the decision recorded on #1311
step 16.
- **The `pypi` environment's deployment-branch rule is not restored**,
per the caveat #1370 records:
its one plausible content would block every `.dev0` publish D3.4
requires.

## Review evidence

21 read-only passes on the strongest tier before this pull request
existed: 11 in round one (10
whole-unit carried-content plus a cross-unit diff pass briefed to hold
`registry/repos.json` open),
9 in round two, and a terminal pair scoped to false claims and
unfollowable instructions. Roughly
220 findings, the large majority introduced by this change and disposed
of in it. The terminal pass
over `GOVERNANCE.md`, `AUDIT.md`, `CODESTYLE.md` and the four skills
returned zero.

The measurement worth recording: **the deletions were right first time
and the reasons drew nearly
everything.** Five claims about GitHub Actions behaviour that this
change introduced were falsified
by the tree and reverted, among them that `always()` and `!failure() &&
!cancelled()` are
interchangeable-with-a-preference (D1.5 *requires* `always()` for the
aggregator), and that the
registry's `releaseTrigger` decides publish-scenario applicability (it
says `two-phase` for this
repository while `publish-release.yml` is `workflow_dispatch:` only).

A carried-content pass is recorded for all 23 canonical units this
change moves.

## Owed on merge

`spec/files.json` declares both edited `GOVERNANCE.md` sections at
`verbatim` fidelity, so every
downstream copy goes stale and a fleet resync follows.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
ptr727 added a commit that referenced this pull request Sep 7, 2026
…sh the WORKFLOW.md Reshape (#1397)

Closes #1205.
Closes #1212.
Closes #1240.
Closes #1250.
Closes #1267.
Closes #1268.
Closes #1271.
Closes #1288.
Closes #1305.
Closes #1314.

Sixteen commits, ten issues. Each was driven as its own feature pull
request into `develop`,
reviewed by the PR-hosted reviewers, and merged only with CI green and
every finding disposed of
by one of the five outcomes: fixed, declined on evidence, decided by the
maintainer, deferred
behind a filed issue, or fixed as a class.

## What this promotes

**The one-home include mechanism and its first six classes** (#1317).
`scripts/build_dist.py`
gained include regions filled from a rule's home and checked by
`--check` (#1378), so a Skill
carries a rule's whole text without a copy that can drift. Classes 2 to
6 then converted the
restatements: `agent-conduct`'s three conduct sections (#1382),
`pr-review-conduct`'s five
outcomes into `drive-pr` with every step-ref renamed to a heading
(#1383),
`backlog-burndown`'s two narrowing rows cut to the narrowing with
fourteen restatements
pointered (#1384), `WORKFLOW.md` section 4 into `workflow-ci-contract`
(#1385), and section 2
cut to a pointer at `GOVERNANCE.md` "Workflow YAML Conventions" (#1388).

**The `WORKFLOW.md` reshape** (#1311 step 14's six-pull-request
sequence, now finished). The
verdict clause aligned with section 5's Assessment (#1390), sections 3
and 5 carried into
`workflow-ci-contract` as generated includes (#1392), 5A collapsed to a
procedure and an evidence
rule (#1394), and the preamble decisions settled alongside the reshape
of section 4, section 6 and
the YAML conventions (#1395). Section 4's two longest items shrank to
their outcomes with the
displaced knowledge moved rather than deleted, and section 6 now states
only what each type adds,
carrying no N/A list at all.

**The review loop's stop rule and disposition policy** (#1330),
rewriting disposal by deletion and
committing the condition under which a whole-unit loop ends, which #1267
filed as missing.

**The Merge Gate's bound on an out-of-diff prose finding**, with the
reviewer footing recorded
(#1333), and reviewer bots scoped away from the generated Skill mirrors
(#1329) so a mirror's diff
is never reviewed in place of its source.

**The fleet label set**, declared and applied through `configure.sh`
(#1334).

**The review ledger and skills digest decoupled from the working tree**
(#1328), so concurrent
branches no longer conflict in a generated report that cannot be
hand-merged.

Plus one grouped Dependabot bump, `docker/setup-qemu-action` 4.2.0 to
4.3.0 (#1325).

## What is deliberately not closed

`#1311`, `#1317`, `#1206`, `#1367`, `#1369`, `#1370`, `#1371`, `#1386`
and `#1237` each still
hold findings this work did not settle. #1317 stands at class 6 of
fourteen, and #1311's step 17
comment records what the reshape filed rather than fixed.

## Owed on merge

`spec/files.json` declares both edited `GOVERNANCE.md` sections at
`verbatim` fidelity, so every
downstream copy goes stale on this promotion and a fleet resync follows
it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants